Skip to main content

OIDC Local Testing with Forge CLI

This guide covers how to locally develop and test OIDC-enabled Aspects using the Forge CLI and the OIDC SSO Toolkit.

Prerequisites​

  • Docker — Docker Desktop (macOS/Windows) or Docker Engine (Linux)
  • Forge CLI — installed via Homebrew or npm/pnpm (see Installation)

Overview​

The Forge CLI integrates the OIDC SSO Toolkit — a Docker-based mock OIDC Identity Provider. When you preview the oidc-snippet template without providing --client-id / --fi-domain, the CLI automatically:

  1. Starts the OIDC Toolkit Docker container.
  2. Waits for the mock IdP to become healthy.
  3. Fetches auto-generated client credentials from the toolkit.
  4. Generates a working snippet targeting localhost:9000.
  5. Registers the snippet in the OLB playground (or serves via local mock).

Quick Start​

Bash
# Zero-config: starts toolkit, fetches credentials, generates working snippet
forge aspect preview --template oidc-snippet

The generated snippet performs a real OIDC authorization code flow against the local toolkit and displays a success toast upon completion.

Managing the Toolkit​

You can also manage the toolkit independently:

Bash
# Start the toolkit
forge oidc up

# Check status, health, and credentials
forge oidc status

# Print credentials (useful for manual testing)
forge oidc credentials
forge oidc credentials --reveal  # show client secret

# Stop the toolkit
forge oidc down

How the Generated Snippet Works​

In toolkit mode (default, no --client-id), the generated JavaScript:

  1. Builds an authorization URL targeting http://localhost:9000/api/auth/authorize.
  2. Sends a fetch() GET request with the auto-generated client_id.
  3. The toolkit returns a JSON response containing an authorization code.
  4. The snippet logs the code to the console.
  5. If a --message was provided, a success toast appears.

In production mode (--client-id + --fi-domain), the snippet targets the real Keycloak endpoint at https://{fi-domain}/auth/realms/{fi-domain}/protocol/openid-connect/auth.

Transitioning to Production​

Once your integration works locally:

  1. Contact your Candescent PM for real FI credentials (client_id, client_secret, endpoint URLs)
  2. Switch to production scaffold:
Bash
forge aspect preview --template oidc-snippet --client-id <pm-provided-id> --fi-domain <fi-domain>
  1. Submit for review:
Bash
forge aspect submit "my-oidc-aspect" --template oidc-snippet --client-id <id> --fi-domain <domain> --env stage

Using the Toolkit with Custom Code​

The toolkit is not limited to the built-in oidc-snippet template. You can point any custom Aspect or widget code to the toolkit endpoints:

EndpointURLMethod
Authorizationhttp://localhost:9000/api/auth/authorizeGET
Tokenhttp://localhost:9000/api/auth/tokenPOST
Client credentialshttp://localhost:9000/api/clientGET
Health checkhttp://localhost:9000/api/healthGET
Bash
# Start the toolkit independently
forge oidc up

# Get credentials for your custom code
forge oidc credentials --json

Port Configuration​

By default, the toolkit uses ports 8000 (configuration UI) and 9000 (mock IdP API). If these ports are occupied, the CLI auto-resolves to the next available port. You can also specify ports manually:

Bash
forge oidc up --backend-port 9001 --frontend-port 8001

Troubleshooting​

IssueCauseSolution
"Port 9000 is in use"Another service on that portStop the conflicting service or use --backend-port 9001
Toolkit not becoming healthyContainer startup slowWait longer, or check docker logs cdx-oidc-toolkit
ARM64 / Apple Silicon warningImage is amd64-onlyNormal — the CLI runs it via emulation automatically
Credentials expired15-minute TTLCredentials auto-regenerate; re-fetch with forge oidc credentials
Docker not runningDocker Desktop not startedStart Docker Desktop and retry

References​